<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3//EN">
<HTML><HEAD>
		<TITLE>User's Reference - SuperviseWindow</TITLE>
		<META HTTP-EQUIV="keywords" CONTENT="GRAPHICS VISUALIZATION VISUAL PROGRAM DATA
MINING">
	<meta http-equiv="content-type" content="text/html;charset=ISO-8859-1">
</HEAD><BODY BGCOLOR="#FFFFFF" link="#00004b" vlink="#4b004b">
		<TABLE width=510 border=0 cellpadding=0 cellspacing=0>
			<TR>
				<TD><IMG src="../images/spacer.gif" width=80 height=1></TD>
				<TD><IMG src="../images/spacer.gif" width=49 height=1></TD>
				<TD><IMG src="../images/spacer.gif" width=24 height=1></TD>
				<TD><IMG src="../images/spacer.gif" width=100 height=1></TD>
				<TD><IMG src="../images/spacer.gif" width=3 height=1></TD>
				<TD><IMG src="../images/spacer.gif" width=127 height=1></TD>
				<TD><IMG src="../images/spacer.gif" width=6 height=1></TD>
				<TD><IMG src="../images/spacer.gif" width=50 height=1></TD>
				<TD><IMG src="../images/spacer.gif" width=71 height=1></TD>
			</TR>
			<TR>
				<TD colspan=9><IMG src="../images/flcgh_01.gif" width=510 height=24 alt="OpenDX - Documentation"></TD>
			</TR>
			<TR>
				<TD colspan=2><A href="../allguide.htm"><IMG src="../images/flcgh_02.gif" width=129 height=25 border="0" alt="Full Contents"></A></TD>
				<TD colspan=3><A href="../qikguide.htm"><IMG src="../images/flcgh_03.gif" width=127 height=25 border="0" alt="QuickStart Guide"></A></TD>
				<TD><A href="../usrguide.htm"><IMG src="../images/flcgh_04.gif" width=127 height=25 border="0" alt="User's Guide"></A></TD>
				<TD colspan=3><B><A href="../refguide.htm"><IMG src="../images/flcgh_05d.gif" width=127 height=25 border="0" alt="User's Reference"></A></B></TD>
			</TR>
			<TR>
				<TD><A href="refgu152.htm"><IMG src="../images/flcgh_06.gif" width=80 height=17 border="0" alt="Previous Page"></A></TD>
				<TD colspan=2><A href="refgu154.htm"><IMG src="../images/flcgh_07.gif" width=73 height=17 border="0" alt="Next Page"></A></TD>
				<TD><A href="../refguide.htm"><IMG src="../images/flcgh_08.gif" width=100 height=17 border="0" alt="Table of Contents"></A></TD>
				<TD colspan=3><A href="refgu009.htm"><IMG src="../images/flcgh_09.gif" width=136 height=17 border="0" alt="Partial Table of Contents"></A></TD>
				<TD><A href="refgu175.htm"><IMG src="../images/flcgh_10.gif" width=50 height=17 border="0" alt="Index"></A></TD>
				<TD><A href="../srchindx.htm"><IMG src="../images/flcgh_11.gif" width=71 height=17 border="0" alt="Search"></A></TD>
			</TR>
		</TABLE>
		<H3><A name="HDRSUPWIND" ></A>SuperviseWindow</H3>
		<P><STRONG>Category</STRONG>
		<P>
<A HREF="refgu008.htm#HDRCATWIN">Windows</A>
<P><STRONG>Function</STRONG>
<P>Creates a Display window for an image and captures
mouse and keyboard events in that window.
<P><STRONG>Syntax</STRONG>
<PRE>
<STRONG>where, size, events</STRONG> = SuperviseWindow(<STRONG>name, display, size,
                                      offset, parent, depth, visibility,
                                      pick, sizeFlag, offsetFlag</STRONG>);
</PRE>
<P><STRONG>Inputs</STRONG>
<BR>
<TABLE BORDER>
<TR>
<TH ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">Name
</TH><TH ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">Type
</TH><TH ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">Default
</TH><TH ALIGN="LEFT" VALIGN="TOP" WIDTH="40%">Description
</TH></TR><TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><TT><STRONG>name</STRONG></TT>
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">string
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">(none)
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="40%">unique name for the window
</TD></TR><TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><TT><STRONG>display</STRONG></TT>
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">string
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">"local host"
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="40%">display on which to create the
window
</TD></TR><TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><TT><STRONG>size</STRONG></TT>
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">integer vector
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">&#91;640,480&#93;
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="40%">x,y size of the window
</TD></TR><TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><TT><STRONG>offset</STRONG></TT>
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">integer vector
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">&#91;0,0&#93;
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="40%">offset of window in parent
</TD></TR><TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><TT><STRONG>parent</STRONG></TT>
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">string
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">(root window)
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="40%">parent window
</TD></TR><TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><TT><STRONG>depth</STRONG></TT>
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">integer
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">8
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="40%">depth of window
</TD></TR><TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><TT><STRONG>visibility</STRONG></TT>
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">integer
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">1
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="40%">visibility of window
</TD></TR><TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><TT><STRONG>pick</STRONG></TT>
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">flag
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">0
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="40%">whether to consider only
button-down events
</TD></TR><TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><TT><STRONG>sizeFlag</STRONG></TT>
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">flag
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">0
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="40%">whether to force the size of an
already existing window
</TD></TR><TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><TT><STRONG>offsetFlag</STRONG></TT>
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">flag
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">0
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="40%">whether to force the offset of an
already existing window
</TD></TR></TABLE>
<P><STRONG>Outputs</STRONG>
<BR>
<TABLE BORDER>
<TR>
<TH ALIGN="LEFT" VALIGN="TOP" WIDTH="25%">Name
</TH><TH ALIGN="LEFT" VALIGN="TOP" WIDTH="25%">Type
</TH><TH ALIGN="LEFT" VALIGN="TOP" WIDTH="50%">Description
</TH></TR><TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="25%"><TT><STRONG>where</STRONG></TT>
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="25%">string
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="50%">where parameter for window
</TD></TR><TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="25%"><TT><STRONG>size</STRONG></TT>
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="25%">integer vector or integer list
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="50%">window size
</TD></TR><TR>
<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="25%"><TT><STRONG>events</STRONG></TT>
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="25%">object
</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="50%">mouse or keyboard events
</TD></TR></TABLE>
<P><STRONG>Functional Details</STRONG>
<P>SuperviseWindow, along with the associated module SuperviseState,
provides the user with direct control over the effect of mouse and
keyboard events in a window containing an image.  SuperviseWindow and
SuperviseState are used together with the Display tool, as an
alternative to the Image tool.
<P>
When you include the Image
tool in a visual program, mouse and keyboard events are interpreted
in a particular way as described in <A HREF="usrgu040.htm#HDRUSEIMAG">6.1 ,
"Using the Image Window"</A> in <I>IBM Visualization Data Explorer User&#39;s
Guide</I>.
In contrast, when
the Supervise modules and
the Display tool are used in a visual program,
you are able to specify how a particular
mouse or keyboard event should affect either the object being viewed or
the camera used to view it. For example, you could specify
that right-mouse drags in a horizontal direction
should zoom in on an object, while right-mouse drags in a vertical
direction should zoom out.
<P>
Not only does this allow you to specify the particular
action that should take place given events in the
display window, but it also allows your interaction with the
image to be separated completely from the Data Explorer user interface.
For example, a completely custom user interface could be created
with a commercial GUI builder, bypassing the Data Explorer user
interface entirely, but still allowing user-interaction with the
image.
<P>
In order to specify custom interaction modes in a program, it is
necessary for you to provide routines which indicate what
action is to be taken for a given event. An action can affect
either the object (for example rotating it or coloring it red), or
the camera (for example zooming in), or both. These sets of user-provided
routines are called UserInteractors. UserInteractors let you
specify your own direct interactors by specifying a table of
callbacks, each implementing a custom interactor.
<P>
To start Data Explorer using custom UserInteractors, it is necessary to identify
the user-written UserInteractor routines to the Data Explorer executive. This is
done by setting the environment variable
<TT>DX_USER_INTERACTOR_FILE</TT> before starting Data Explorer.
(You can also load UserInteractors after starting Data Explorer by using the
Executive module (<A HREF="refgu055.htm#HDREXECTV">Executive</A> in <I>IBM
Visualization Data Explorer User&#39;s Reference</I>)).
<P>
If you do not set the <TT>DX_USER_INTERACTOR_FILE</TT> environment
variable, a set of default interactors are provided automatically by
Data Explorer. These interactors provide Rotate, Pan, and Zoom functions.
<P>
See <A HREF="refgu152.htm#HDRSUPSTAT">SuperviseState</A> for more detailed
information on how to specify UserInteractors.
SuperviseWindow and SuperviseState should not be used in -image mode
of Data Explorer. If used in -image mode, they will compete for ownership
of the Image window with the User Interface. Use -edit  or -menubar mode
instead.
<TABLE CELLPADDING="3">
<TR VALIGN="TOP"><TD><P><B><TT><STRONG>name</STRONG></TT>
</B></TD><TD><P>is a unique name for the window.
</TD></TR><TR VALIGN="TOP"><TD><P><B><TT><STRONG>display</STRONG></TT>
</B></TD><TD><P>is the display on which to create the window and defaults
to "local host".
</TD></TR><TR VALIGN="TOP"><TD><P><B><TT><STRONG>size</STRONG></TT>
</B></TD><TD><P>is the x,y size of the window, and defaults to 640x480. It can
be specified either as an integer vector or as an integer list.
</TD></TR><TR VALIGN="TOP"><TD><P><B><TT><STRONG>offset</STRONG></TT>
</B></TD><TD><P>is the offset of the window in the parent window. By default,
<TT><STRONG>offset</STRONG></TT> is &#91;0,0&#93;. It can be specified
either as an integer vector or as an integer list.
</TD></TR><TR VALIGN="TOP"><TD><P><B><TT><STRONG>parent</STRONG></TT>
</B></TD><TD><P>is the parent window "where" parameter;
<TT><STRONG>parent</STRONG></TT>
defaults to the root window, but can also be an already created window if
nested windows are desired.
</TD></TR><TR VALIGN="TOP"><TD><P><B><TT><STRONG>depth</STRONG></TT>
</B></TD><TD><P>is the depth (in bits) of the window;
<TT><STRONG>depth</STRONG></TT>
defaults to 8.
</TD></TR><TR VALIGN="TOP"><TD><P><B><TT><STRONG>visibility</STRONG></TT>
</B></TD><TD><P>indicates the visibility of the window:
<TABLE CELLPADDING="3">
<TR VALIGN="TOP"><TD><B>0
</B></TD><TD>window is closed
</TD></TR><TR VALIGN="TOP"><TD><B>1
</B></TD><TD>window is open
</TD></TR><TR VALIGN="TOP"><TD><B>2
</B></TD><TD>window is open and always on top
</TD></TR></TABLE>
</TD></TR><TR VALIGN="TOP"><TD><P><B><TT><STRONG>pick</STRONG></TT>
</B></TD><TD><P>indicates whether only button-down events should be considered.
This
is useful if the user wants to implement picking in the Display window.
</TD></TR><TR VALIGN="TOP"><TD><P><B><TT><STRONG>sizeFlag</STRONG></TT>
</B></TD><TD><P>indicates  whether to force the size of an already existing
window.
The default is 0 (false).
</TD></TR><TR VALIGN="TOP"><TD><P><B><TT><STRONG>offsetFlag</STRONG></TT>
</B></TD><TD><P>indicates  whether to force the offset of an already existing
window. The default is 0 (false).
</TD></TR><TR VALIGN="TOP"><TD><P><B><TT><STRONG>where</STRONG></TT>
</B></TD><TD><P>identifies the window. This output must be connected to the
<TT><STRONG>where</STRONG></TT>
parameter of the Display tool. It would also be used, for example, if
nested windows are desired using a SuperviseWindow module with the
<TT><STRONG>parent</STRONG></TT> parameter set to something other than the
root window.
</TD></TR><TR VALIGN="TOP"><TD><P><B><TT><STRONG>size</STRONG></TT>
</B></TD><TD><P>is the current size of the window, and may differ from the
<TT><STRONG>size</STRONG></TT>
input if you resize the window.
</TD></TR><TR VALIGN="TOP"><TD><P><B><TT><STRONG>events</STRONG></TT>
</B></TD><TD><P>encodes mouse or keyboard events. It is an array of integer
of integer 4-vectors, where the four integers represent the following:
<UL COMPACT>
<LI>event
<LI>x
<LI>y
<LI>state or keypress, depending on event
</UL>
<TT><STRONG>event</STRONG></TT> is one of <TT>DXEVENT_LEFT</TT>,
<TT>DXEVENT_MIDDLE</TT>, <TT>DXEVENT_RIGHT</TT>, or
<TT>DXEVENT_KEYPRESS</TT>. <TT><STRONG>x</STRONG></TT> and
<TT><STRONG>y</STRONG></TT> are the pixel locations of the event.
For <TT><STRONG>event</STRONG></TT> = <TT>DXEVENT_LEFT</TT>,
<TT>DXEVENT_MIDDLE</TT>, <TT>DXEVENT_RIGHT</TT>, the final integer
is "state", which is one of <TT>BUTTON_UP</TT>,
<TT>BUTTON_MOTION</TT>, or <TT>BUTTON_DOWN</TT>.
For <TT><STRONG>event</STRONG></TT> = <TT>DXEVENT_KEYPRESS</TT>, the final
integer is "keypress" which is the character which was pressed.
Note that
<PRE>
#define DXEVENT_LEFT            0x01
#define DXEVENT_MIDDLE          0x02
#define DXEVENT_RIGHT           0x04
#define DXEVENT_KEYPRESS        0x08
#define BUTTON_UP               1
#define BUTTON_DOWN             2
#define BUTTON_MOTION           3
</PRE>
<P>
<P>
For operations other than picking, the user simply passes
<TT><STRONG>events</STRONG></TT> to the <TT><STRONG>events</STRONG></TT>
input of SuperviseState, which interprets the mouse or keyboard events
and calls the appropriate user routines. For picking, see
<A HREF="refgu152.htm#HDRPICKING">"Doing Picking"</A>.
</TD></TR></TABLE>
<P><STRONG>Example Visual Programs</STRONG>
<P>
<PRE>
SIMPLE/Supervise.net
Image_wo_UI.net
IndependentlyArrange.net
InsetImage.net
</PRE>
Also see the demonstrations of custom interactors in
<TT>/usr/local/dx/samples/supervise</TT>.
<P><STRONG>See Also</STRONG>
<P>
<A HREF="refgu152.htm#HDRSUPSTAT">SuperviseState</A>,
<A HREF="refgu048.htm#HDRDISPLAY">Display</A>,
<A HREF="refgu072.htm#HDRIMAGE">Image</A>
		<P>
		<HR>
		<DIV align="center">
			<P><A href="../allguide.htm"><IMG src="../images/foot-fc.gif" width="94" height="18" border="0" alt="Full Contents"></A> <A href="../qikguide.htm"><IMG src="../images/foot-qs.gif" width="94" height="18" border="0" alt="QuickStart Guide"></A> <A href="../usrguide.htm"><IMG src="../images/foot-ug.gif" width="94" height="18" border="0" alt="User's Guide"></A> <A href="../refguide.htm"><IMG src="../images/foot-ur.gif" width="94" height="18" border="0" alt="User's Reference"></A></P>
		</DIV>
		<DIV align="center">
			<P><FONT size="-1">[ <A href="http://www.research.ibm.com/dx">OpenDX Home at IBM</A>&nbsp;|&nbsp;<A href="http://www.opendx.org/">OpenDX.org</A>&nbsp;] </FONT></P>
			<P></P>
		</DIV>
		<P></P>
	</BODY></HTML>
